/*
 * JBoss, Home of Professional Open Source
 * Copyright 2010, Red Hat, Inc., and individual contributors
 * by the @authors tag. See the copyright.txt in the distribution for a
 * full listing of individual contributors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,  
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package javax.enterprise.context.spi;

import javax.enterprise.inject.CreationException;
import javax.enterprise.inject.spi.Bean;

/**
 * <p>
 *    定义在创建和销毁特定的上下文类型时具体的操作.
 *    任何继承{@code Contextual}都是一个上下文类型, 特别说明，所有的bean都是上下文实例
 * </p>
 * 
 * @see Bean
 * 
 * @author Gavin King
 * @author Nicklas Karlsson
 * @author Pete Muir
 * @param <T> 上下文实例类型
 */
public interface Contextual<T> {
    /**
     * 创建一个新的上下文类型的实例.
     *
     * 实例在获取注入的上下文引用时应使用给定的CreationalContext操作，以确保任何依赖对象与正在创建的上下文实例相关联.(ps:也是防止循环依赖注入的一个有效方法)
     *
     * 一个上下文实例可能会在注入和初始化这两个过程之间调用{@link CreationalContext#push(Object)}方法，来帮助容器最小化客户端代理对象的使用
     *
     *
     * @param creationalContext 正在创建实例的 CreationalContext
     * @return 上下文实例
     * @throws CreationException 如果在创建实例时发生检查异常,则抛出该异常
     */
    public T create(CreationalContext<T> creationalContext);

    /**
     * 销毁一个上下文类型实例.该实例应该调用 {@link CreationalContext#release()} 方法，来让容器销毁其依赖的其他上下文实例
     * 
     * @param instance 准备销毁的上下文实例
     * @param creationalContext 该实例创建时的CreationalContext
     */
    public void destroy(T instance, CreationalContext<T> creationalContext);
}
